<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>legendre</title>
  </head>
  <body bgcolor="#FFFFFF">
    <center>Scilab Function  </center>
    <div align="right">Last update : 16/12/2004</div>
    <p>
      <b>legendre</b> - associated Legendre functions</p>
    <h3>
      <font color="blue">Calling Sequence</font>
    </h3>
    <dl>
      <dd>
        <tt> y = legendre(n,m,x [,normflag]) </tt>
      </dd>
    </dl>
    <h3>
      <font color="blue">Parameters</font>
    </h3>
    <ul>
      <li>
        <tt>
          <b>n</b>
        </tt>: non negative integer or vector of non negative integers regularly spaced with increment equal to 1</li>
      <li>
        <tt>
          <b>m</b>
        </tt>: non negative integer or vector of non negative integers regularly spaced with increment equal to 1</li>
      <li>
        <tt>
          <b>x</b>
        </tt>: real (row) vector (elements of <tt>
          <b>x</b>
        </tt> must be in the <tt>
          <b>(-1,1)</b>
        </tt> interval)</li>
      <li>
        <tt>
          <b>normflag</b>
        </tt>: (optional) scalar string</li>
    </ul>
    <h3>
      <font color="blue">Description</font>
    </h3>
    <p>
    When <tt>
        <b>n</b>
      </tt> and <tt>
        <b>m</b>
      </tt> are scalars, 
    <tt>
        <b>legendre(n,m,x)</b>
      </tt> evaluates the associated Legendre 
    function Pnm(x) at all the elements of <tt>
        <b>x</b>
      </tt>. The definition used 
    is :
  </p>
    <pre>
                              m
               m        m/2  d  
  Pnm(x) = (-1)  (1-x^2)    --- Pn(x)
                              m  
                            dx 
     </pre>
    <p>
     where <tt>
        <b>Pn</b>
      </tt> is the Legendre polynomial of degree <tt>
        <b>n</b>
      </tt>. So 
     <tt>
        <b>legendre(n,0,x)</b>
      </tt> evaluates the Legendre polynomial Pn(x) at all 
     the elements of <tt>
        <b>x</b>
      </tt>. 
  </p>
    <p>
     When the normflag is equal to "norm" you get a normalized version (without
    the <tt>
        <b>(-1)^m</b>
      </tt> factor), precisely :
  </p>
    <pre>
                     _____________                m
                    /(2n+1)(n-m)!          m/2   d
  Pnm(x,"norm") =  /--------------  (1-x^2)     --- Pn(x)
                 \/     2  (n+m)!                 m
                                                dx 
     </pre>
    <p>
     which is useful to compute spherical harmonic functions (see Example 3):
  </p>
    <p>
     For efficiency, one of the two first arguments may be a vector, for instance
     <tt>
        <b>legendre(n1:n2,0,x)</b>
      </tt> evaluates all the Legendre polynomials of
     degree <em>n1, n1+1, ..., n2</em> at the elements of <tt>
        <b>x</b>
      </tt> and
     <tt>
        <b>legendre(n,m1:m2,x)</b>
      </tt> evaluates all the Legendre associated 
     functions Pnm for <em>m=m1, m1+1, ..., m2</em> at <tt>
        <b>x</b>
      </tt>.
  </p>
    <h3>
      <font color="blue">Output format</font>
    </h3>
    <dl>
      <p>
    In any case, the format of <tt>
          <b>y</b>
        </tt> is :
    </p>
      <pre>
        max(length(n),length(m)) x length(x)
     </pre>
      <p>
    and :
    </p>
      <pre>
       y(i,j) = P(n(i),m;x(j))   if n is a vector
       y(i,j) = P(n,m(i);x(j))   if m is a vector
       y(1,j) = P(n,m;x(j))      if both n and m are scalars
     </pre>
      <p>
     so that <tt>
          <b>x</b>
        </tt> is preferably a row vector but any <tt>mx x nx</tt> matrix
     is excepted and considered as an <tt>1 x (mx * nx)</tt> matrix, reshaped
     following the column order.
     </p>
    </dl>
    <h3>
      <font color="blue">Examples</font>
    </h3>
    <pre>
// example 1 : plot of the 6 first Legendre polynomials on (-1,1)
l = nearfloat("pred",1);
x = linspace(-l,l,200)';
y = legendre(0:5, 0,  x);
xbasc()
plot2d(x,y', leg="p0@p1@p2@p3@p4@p5@p6")
xtitle("the 6 th first Legendre polynomials")

// example 2 : plot of the associated Legendre functions of degree 5 
l = nearfloat("pred",1);
x = linspace(-l,l,200)';
y = legendre(5, 0:5, x, "norm");
xbasc()
plot2d(x,y', leg="p5,0@p5,1@p5,2@p5,3@p5,4@p5,5")
xtitle("the (normalised) associated Legendre functions of degree 5")

// example 3 : define then plot a spherical harmonic
// 3-1 : define the function Ylm
function [y] = Y(l,m,theta,phi)
   // theta may be a scalar or a row vector
   // phi may be a scalar or a column vector
   if m &gt;= 0 then
      y = (-1)^m/(sqrt(2*%pi))*exp(%i*m*phi)*legendre(l, m, cos(theta), "norm")
   else
      y = 1/(sqrt(2*%pi))*exp(%i*m*phi)*legendre(l, -m, cos(theta), "norm")
   end      
endfunction

// 3.2 : define another useful function
function [x,y,z] = sph2cart(theta,phi,r)
   // theta row vector      1 x nt
   // phi   column vector  np x 1
   // r     scalar or np x nt matrix (r(i,j) the length at phi(i) theta(j)) 
   x = r.*(cos(phi)*sin(theta));
   y = r.*(sin(phi)*sin(theta));
   z = r.*(ones(phi)*cos(theta));
endfunction

// 3-3 plot Y31(theta,phi)
l = 3; m = 1;
theta = linspace(0.1,%pi-0.1,60);
phi = linspace(0,2*%pi,120)';
f = Y(l,m,theta,phi);
[x1,y1,z1] = sph2cart(theta,phi,abs(f));       [xf1,yf1,zf1] = nf3d(x1,y1,z1);
[x2,y2,z2] = sph2cart(theta,phi,abs(real(f))); [xf2,yf2,zf2] = nf3d(x2,y2,z2);
[x3,y3,z3] = sph2cart(theta,phi,abs(imag(f))); [xf3,yf3,zf3] = nf3d(x3,y3,z3);

xbasc()
subplot(1,3,1)
plot3d(xf1,yf1,zf1,flag=[2 4 4]); xtitle("|Y31(theta,phi)|")
subplot(1,3,2)
plot3d(xf2,yf2,zf2,flag=[2 4 4]); xtitle("|Real(Y31(theta,phi))|")
subplot(1,3,3)
plot3d(xf3,yf3,zf3,flag=[2 4 4]); xtitle("|Imag(Y31(theta,phi))|")
 </pre>
    <h3>
      <font color="blue">Authors</font>
    </h3>
    <dl>
      <dd>
        <b></b>Smith, John M. (code dxlegf.f from Slatec)</dd>
      <dd>
        <b></b>B. Pincon (scilab interface)</dd>
    </dl>
  </body>
</html>
